/*
 * Copyright 2009 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.splink.deepsplink.boot {
	import org.splink.deepsplink.authentication.IAuthenticator;
	import org.splink.deepsplink.config.ConfigData;
	import org.splink.deepsplink.injector.IPageInjector;
	import org.splink.deepsplink.interceptor.IInterceptor;
	import org.splink.deepsplink.navigation.command.INavigationCommand;
	import org.splink.deepsplink.processor.IProcessor;
	import org.splink.library.tree.Tree;

	import flash.display.DisplayObject;

	/**
	 * Wires deepsplink components and provides clients with centralized access to 
	 * the public deepsplink API. 
	 * 
	 * @author Max Kugland
	 */
	public interface IDeepsplinkFacade {
		
		/**
		 * Adds an <code>IInterceptor</code> implementation. Before a page change happens, all 
		 * previously added <code>IInterceptor</code> are consulted whether the page change request
		 * is permitted.
		 * 
		 * @param interceptor an <code>IInterceptor</code> implementation
		 * 
		 * @see org.splink.deepsplink.interceptor.IInterceptor
		 */
		function addInterceptor(interceptor : IInterceptor) : void;
		
		/**
		 * Adds an <code>IPageInjector</code> which is useful if you need to inject additional 
		 * dependencies into a page. The injector is executed immediately after the instantiation
		 * of a page. Therefore it is neccessary to add the injector before the pages are instantiated.
		 * Usually that is while the <code>IBootStrategy</code>'s boot method executes. If you try
		 * to add an injector too late an <code>Error</code> is thrown.
		 * 
		 * @param injector the <code>IPageInjector</code>
		 * @see org.splink.deepsplink.injector.IPageInjector
		 */
		function addInjector(injector : IPageInjector) : void;
		
		/**
		 * Adds an <code>IProcessor</code>. Added <code>IProcessor</code> implementations are
		 * informed about each page change.
		 * 
		 * @param processor an <code>IProcessor</code> implementation
		 * @see org.splink.deepsplink.processor.IProcessor
		 */
		function addProcessor(processor : IProcessor) : void;
		
		/**
		 * Registeres an <code>IAuthenticator</code> implementation, which is mandatory if 
		 * protected pages are configured. There is a convenience base class named 
		 * <code>BaseAuthenticator</code>.
		 * 
		 * @param authenticator the <code>IAuthenticator</code> implementation.
		 * 
		 * @see org.splink.deepsplink.authentication.IAuthenticator
		 * @see org.splink.deepsplink.authentication.BaseAuthenticator
		 */		
		function registerAuthenticator(authenticator : IAuthenticator) : void;
		
		/**
		 * Returns the <code>Tree</code> instance which is a representation of the page 
		 * structure. The tree consists of <code>Node</code> instances, whose 
		 * data property holds the title of the page.
		 * 
		 * @return tree the tree
		 * 
		 * @see org.splink.library.tree.Node
		 * @see org.splink.library.tree.Tree
		 * @see org.splink.deepsplink.navigation.IPageNavigationModel
		 */
		function get tree() : Tree;
		
		/**
		 * @return an <code>INavigationCommand</code> implementation
		 */
		function get navigationCommand() : INavigationCommand;
		
		/**
		 * @return the <code>DisplayObject</code> which contains the page displays
		 */
		function get display() : DisplayObject;
		
		/**
		 * Config data is the object representation of the deepsplink xml configuration.
		 * 
		 * @return a clone of the deepsplink configuration
		 */
		function get config() : ConfigData;
		
		/**
		 * Finalizes the complete deepsplink framework, including all pages.
		 */
		function finalize() : void
	}
}
